Welcome to the world of ViewIt‚Ñ¢. The "Startup" topics contain basic information that you should only need to learn once. Please read all of the information presented here before you attempt to read other on-line help or make use of ViewIt to open windows within your programs.
What Is ViewIt?
The ViewIt product is shipped with two main programming modules: ViewIt‚Ñ¢ and FaceIt‚Ñ¢. The ViewIt module is one of the most powerful and elegant Macintosh programming tools available for creating and supporting sophisticated windows. The FaceIt module adds support for modeless windows, the main menu bar, background processing, and other features.
About On-Line Help
The "ViewIt On-Line Help" window is a combination debugging, project, and help window. It has no effect on program operation and can be completely removed from finished programs.
• The Help Control
This window presents on-line documentation or "help" in a "control" that is part of a ViewIt window. The help control in this window consists of the box containing this text and the scroll bar at the right. Most of the other controls in this window display icons or text that support pull-down menus. These menus contain standard items such as "Save", "Cut", etc., and other items that can be used to display other topics in this help control.
• Getting Around
ViewIt documentation is divided into several "guides" that correspond to the menus at the top of this window: "Startup", "ViewIt", "FaceIt", etc. Each guide contains several "topics" that are shown in the guide's menu. Many topics also contain "subtopics" that will appear in a hierarchical menu attached to the topic item after that item is selected (i.e., choose a topic to jump to, and then select the menu again to see if a hierarchical menu of subtopics appears). Some of the more important topics can also be accessed from the "Quick Help" menu at the bottom of the window.
• Why On-Line Help?
All ViewIt documentation is presented in help controls like this one. This help can be easily printed to produce printed manuals (use "Print All" to print all topics). The use of on-line help (versus printed manuals) allows us to more quickly respond to your suggestions and changing needs, and also supports features such as searching (try "Find..." item above) and context-sensitive help that cannot be done with printed manuals.
• Editing Help
As shown by the lock icon at the top, right of this help control, this help text is not editable, although you can change fonts and styles to enhance printed output. Many of the disabled editing options in this window's menus were kept to make it easier for us to edit this help and are not intended for your use. When using help controls in your own programs, you can make help text editable or not, and choose to hide the lock icon. (After becoming more familiar with ViewIt, you can learn more about help controls by choosing "HelpCt" in the "Drivers" menu.)
Debugging Aids
In addition to displaying on-line help, the "ViewIt On-Line Help" window provides information about the program state, support for creating and editing windows, display of commands and messages, and an "Interrupt" button to help with debugging.
• Program State
The 3 icons at the top right are pull-down menus that present information about the state of the program: program-wide options (diamond icon), menus available (menu icon), and windows available (window icon). The program options and menus are set and edited outside the program, but windows are created and edited on-line.
• Command Display
Programs communicate with FaceWare modules via high-level commands. To help with debugging, most ViewIt commands that get executed are displayed at the bottom of the window (DrwCtl and utility commands are not displayed since these are used so frequently by other commands that displaying them would be confusing). The most common commands displayed are DoLoop (main event loop), NewWnd (open window), MdlWnd (run modal window), and EndWnd (close modal window). Note that not all commands displayed will have been executed by your program since the displayed commands include those that ViewIt itself executes to support its own built-in windows.
• Message Display
Programs that use FaceIt and ViewIt must respond to special messages posted by these modules when an event occurs that these modules do not know how to handle. To help you with debugging, the 3 main types of messages returned are displayed at the bottom of this window as they are posted: Window events in blue, Menu events in green, and other Messages in red. Note that not all of the messages displayed will be returned to your program since they include messages that occur when ViewIt is calling itself recursively to support its own modal windows.
• Interrupt Button
The "Interrupt" button can be used to stop all messages from being returned to your program until it is pressed again. The messages still appear at the bottom of this window, however, so that you can experiment without affecting your program.
"Save Help Settings" from the pop-up menu at the bottom of this window can be used to save the current window position, size, and help topic. In addition, if the "Interrupt" button has been set (i.e., its title is "Continue"), then saving settings will also save this interrupt state. In this case, the next time the program is run, execution will stop on DoInit (described in later topics) until the button is hit to continue. You can also cause execution to stop on DoInit by simply having the OPTION key pressed while this help window is being opened.
Interrupting program execution on DoInit is useful in cases where program code has been changed that requires editing a window before code beyond DoInit can be executed. The new code, for example, might depend upon the presence of a button that has not yet been added to a window. By interrupting the program on DoInit, you could use the window icon menu above to edit the window before executing the changed code.
Read Startup Topics
The above "Startup" menu can be used to open other help topics dealing with getting started. Topics 2-5 present basic information about FaceWare modules, 6-10 describe the minimum code needed to open a ViewIt window in a FaceIt-based program, and the "Summary" topic presents an overview of the entire process of creating or modifying programs to make use of ViewIt, FaceIt, and other modules.
Other features of ViewIt and FaceIt are described in the topics listed in the other pull-down menus. Resist trying to read this more detailed help until you understand the information in the startup topics.
Recompiling Demos
Once you've read the startup topics, a good first step is to attempt to recompile and run one of our demo programs. Some typical problems encountered include:
• PROBLEM: Message "FCMD/FACE 1210 v2.2 not found..." appears indicating that part of the ViewIt module (FACE 1210) was not found. CAUSE: The "FaceWare" file was not placed in a spot where the program could find it.
• PROBLEM: The program immediately quits back to the Finder when launched. CAUSE: LoadIt could not be found, usually because the program's ".Rsrc" file was not found.
• PROBLEM: The program immediately crashes when launched under System 7 or MultiFinder. POSSIBLE CAUSE: The program's partition size is too small. FaceWare modules use heap memory in addition to that used by the main program.
Once you have gotten one of the demo programs to compile and run, then it is easy to either add your own code to it, or to add the little code needed to support FaceWare modules to existing programs.
Shareware Limits
If working with the shareware version, please choose the "Legal Stuff" item from the "Startup" menu above to learn about what you can and cannot do with this version.
In addition to the limits on how programs developed with the shareware version can be distributed, and on the level of support provided by FaceWare, the shareware version is missing several files that are included with the purchased version of ViewIt. Most of these files, however, deal with advanced features or the final stages of developement, so you won't find yourself limited in any important way when trying the shareware version.
The files missing from the shareware version that affect the final stages of development include:
- the "fDemoLP+" and "Finder.Rsrc" files discussed in the "Finder Resources" topic of the FaceIt Guide
- the "hmnu TMPL" file used to create menu item balloon help discussed in the "Menu Handling" topic of the FaceIt Guide
- the non-editing version of the FaceWare file discussed in the "Resources" topic of the ViewIt Guide
The files missing from the shareware version that deal with advanced ViewIt features include:
- the C++, C, and Pascal examples of program-driven controls discussed in the "Override" topic of the ViewIt Guide
- the files from the "FaceStub Stuff" folder discussed in the "Hybrid Programs" topic of the FaceIt Guide
Other files missing from the shareware version include:
- a C++ "VDocument" base class project that can be used to help manage document files and windows
